{ "openapi": "3.0.0", "info": { "title": "Marketplace API", "description": "The **Marketplace API** enables marketplaces and sellers hosted on VTEX to perform their collaborative operations. \r\n\r\n>⚠️ The marketplace must [create an appKey and appToken](https://developers.vtex.com/docs/guides/getting-started-authentication) for each non-VTEX seller that will use this API.\r\n\r\n## Index\r\n\r\n### Notification\r\n\r\nEndpoints used by sellers to notify marketplaces that the price or inventory language has changed for one of their SKUs.\r\n\r\n`POST` [Notify marketplace of price update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price)\r\n\r\n`POST` [Notify marketplace of inventory update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory)\r\n\r\n\r\n### Suggestions\r\n\r\n#### Get Suggestions\r\n\r\nSearch and filter all suggestions using specific criteria.\r\n\r\n`GET` [Get all SKU Suggestions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions)\r\n\r\n`GET` [Get SKU Suggestion by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerSkuId-)\r\n\r\n\r\n#### Manage Suggestions\r\n\r\nSend or delete SKU suggestions from the seller to marketplace.\r\n\r\n`PUT` [Send SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerSkuId-)\r\n\r\n`DELETE` [Delete SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#delete-/suggestions/-sellerId-/-sellerSkuId-)\r\n\r\n\r\n#### Get Versions\r\n\r\nSearch and filter all versions of suggestions, using specific criteria.\r\n\r\n`GET` [Get all versions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions)\r\n\r\n`GET` [Get version by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions/-version-)\r\n\r\n\r\n#### Match Received SKUs\r\n\r\nMatch SKU suggestions received in the marketplace.\r\n\r\n`PUT` [Match Received SKUs individually](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerskuid-/versions/-version-/matches/-matchid-)\r\n\r\n`PUT` [Match Multiple Received SKUs](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/matches/action/-actionName-)\r\n\r\n\r\n#### SKU Approval Settings\r\n\r\nAllows marketplaces to configure rules for automatically and manually approving SKUs received from sellers.\r\n\r\n`GET`[Get autoApprove Status in Account Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/autoapproval/toggle) \r\n\r\n`PUT`[Activate autoApprove in Marketplace's Account](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle) \r\n\r\n`GET`[Get Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration)\r\n\r\n`PUT`[Save Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration)\r\n\r\n`GET`[Get Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/seller/-sellerId-)\r\n\r\n`PUT`[Save Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/seller/-sellerId-)\r\n\r\n`PUT`[Activate autoApprove Setting for a Seller](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle/seller/-sellerId-) \r\n\r\n\r\n### Matched Offers\r\n\r\nOffers are seller products and SKUs that were sent to the marketplace, and already have their price and inventory level configured.\r\n\r\n`GET`[Get Matched Offers List](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/offers)\r\n\r\n`GET`[Get Matched Offer's Data by SKU ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-/sku/-skuId-) \r\n\r\n`GET`[Get Matched Offer's Data by Product ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-)\r\n", "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br/api", "description": "VTEX Server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/notificator/{sellerId}/changenotification/{skuId}/price": { "post": { "tags": [ "Notification" ], "summary": "Notify marketplace of price update", "description": "This endpoint is used by *sellers* to notify marketplaces that the price has changed for one of their SKUs. \r\n\r\nThere is no request body in this call, indicating the new price value, for instance. It only notifies a specific marketplace (`accountName`) that a seller (`sellerId`) has changed the price of an SKU (`skuId`). \r\n\r\n*Marketplaces* will then call the [fulfillment endpoint](https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation) provided in the seller registration form to get the updated price information.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "PriceNotification", "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/sellerId" }, { "$ref": "#/components/parameters/skuId" } ], "responses": { "202": { "description": "Accepted" } }, "deprecated": false } }, "/notificator/{sellerId}/changenotification/{skuId}/inventory": { "post": { "tags": [ "Notification" ], "summary": "Notify marketplace of inventory update", "description": "This endpoint is used by *sellers* to notify marketplaces that the inventory level has changed for one of their SKUs. \n\nThere is no request body in this call, indicating the new inventory level, for instance. It only notifies a specific marketplace (`accountName`) that a seller (`sellerId`) has changed the inventory level of an SKU (`skuId`). \n\n*Marketplaces* will then call the [fulfillment endpoint](https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation) provided in the seller registration form to get the updated inventory information.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "InventoryNotification", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/sellerId" }, { "$ref": "#/components/parameters/skuId" } ], "responses": { "202": { "description": "Accepted" } }, "deprecated": false } }, "/offer-manager/pvt/offers": { "get": { "tags": [ "Matched Offers" ], "summary": "Get matched offers list", "description": "Offers are seller's products and SKUs that were sent to the marketplace, and already have their price and inventory level configured. \n\n This endpoint retrieves the available offers in a marketplace. It differs from the Get Suggestions endpoints, since it retrieves products that were already matched by the marketplace, and are currently in its catalog. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "Getofferslist", "parameters": [ { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/rows" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/fq" }, { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseGetMatchedOffersList" }, "example": [ { "LastModified": "2021-05-06T21:37:24.262529", "ProductId": "941947", "CategoryId": 1563, "BrandId": 2004291, "ProductName": "Product Test 04 - Black - 40", "Skus": [ { "SkuId": "1070268", "EanId": "768655", "RefId": "1234", "NameComplete": "Product Test 04 - Black - 40 Color:Black", "Name": "Color:Black", "IsActive": true, "MainImage": { "ImageId": "53878805", "ImageLabel": null, "ImageTag": "\"image-8b4364782e664d76a6ebc8702008e478\"", "ImagePath": "~/arquivos/ids/53878805-#width#-#height#/image-8b4364782e664d76a6ebc8702008e478.jpg", "IsMain": true, "IsZoomSize": true, "ImageText": "image-8b4364782e664d76a6ebc8702008e478", "LastModified": "2021-04-06T03:01:30.747" }, "Offers": [ { "SellerId": "1", "SellerSkuId": "1070268", "OffersPerSalesChannel": [ { "SaleChannel": 1, "Price": 0, "ListPrice": 0, "PriceWithoutDiscount": 0, "AvailableQuantity": 0 } ], "AvailableSalesChannels": null }, { "SellerId": "madesacms", "SellerSkuId": "3298", "OffersPerSalesChannel": [ { "SaleChannel": 0, "Price": 1200, "ListPrice": 1200, "PriceWithoutDiscount": 1200, "AvailableQuantity": 10000000 } ], "AvailableSalesChannels": null } ] } ] } ] } } } }, "deprecated": false } }, "/offer-manager/pvt/product/{productId}/sku/{skuId}": { "get": { "tags": [ "Matched Offers" ], "summary": "Get matched offers' data by SKU ID", "description": "Offers are seller products and SKUs that were sent to the marketplace, and already have their price and inventory level configured. \n\nThis endpoint retrieves the available offers for a speciic SKU ID in the marketplace's catalog. It differs from the [Get Suggestions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions/#get-/suggestions) endpoints, since it retrieves products that were already matched by the marketplace operator, and are currently active in its catalog. \n\nThe call returns a list of offers for that ID, that contain the following data: \n\n- Seller that sells the SKU \n\n- Correspondent SKU ID \n\n- SKU's price value \n\n- Inventory level \n\n- Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) that it is available at. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "GetSKUoffers", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/productId" }, { "$ref": "#/components/parameters/skuId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseGetMatchedOffersDataBySKU" }, "example": [ { "productId": "1561208", "skuId": "1559161", "nameComplete": "Long sleeve cardigan - Women - Grey - L", "mainImage": { "imagePath": "~/arquivos/ids/8567753-#width#-#height#/image-05b40d3167b5b7ed42285124f6862f12.jpg" }, "sellersOffers": [ { "sellerId": "1", "sellerSkuId": "1559161", "salesChannelOffer": [ { "salesChannelId": "1", "salesChannelName": "Principal", "price": 49.99, "listPrice": 59.99, "priceWithoutDiscount": 49.99, "availableQuantity": 8 }, { "salesChannelId": "2", "salesChannelName": "Online Store", "price": 47.99, "listPrice": 59.99, "priceWithoutDiscount": 47.99, "availableQuantity": 12 } ] } ] } ] } } } }, "deprecated": false } }, "/offer-manager/pvt/product/{productId}": { "get": { "tags": [ "Matched Offers" ], "summary": "Get matched offers' data by product ID", "operationId": "GetProductoffers", "description": "Offers are seller products and SKUs that were sent to the marketplace, and already have their price and inventory level configured. \n\nThis endpoint retrieves the available offers for a speciic Product ID in the marketplace's catalog. It differs from the Get Suggestions endpoints, since it retrieves products that were already matched by the marketplace operator, and are currently active in its catalog. \n\nThe call returns a list of offers for that ID, that contain the following data: \n\n- Seller that sells the SKU \n\n- Correspondent SKU ID \n\n- SKU's price value \n\n- Inventory level \n\n- Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) that it is available at.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/productId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseGetMatchedOffersDataByProductId" }, "example": [ { "productId": "1561208", "skuId": "1559161", "nameComplete": "Long sleeve cardigan - Women - Grey - L", "mainImage": { "imagePath": "~/arquivos/ids/8567753-#width#-#height#/image-05b40d3167b5b7ed42285124f6862f12.jpg" }, "sellersOffers": [ { "sellerId": "1", "sellerSkuId": "1559161", "salesChannelOffer": { "salesChannelId": "1", "salesChannelName": "Principal", "price": 0.0, "listPrice": 0.0, "priceWithoutDiscount": 0.0, "availableQuantity": 0 } } ] }, { "productId": "1561208", "skuId": "1559163", "nameComplete": "Long sleeve cardigan - Women - Grey - XS", "mainImage": { "imagePath": "~/arquivos/ids/8567753-#width#-#height#/image-05b40d3167b5b7ed42285124f6862f12.jpg" }, "sellersOffers": [ { "sellerId": "1", "sellerSkuId": "1559161", "salesChannelOffer": { "salesChannelId": "1", "salesChannelName": "Principal", "price": 0.0, "listPrice": 0.0, "priceWithoutDiscount": 0.0, "availableQuantity": 0 } } ] } ] } } } }, "deprecated": false } }, "/seller-register/pvt/seller-leads": { "post": { "tags": [ "Seller Invite" ], "summary": "Invite seller lead", "description": "This API is used by marketplace operators to invite sellers to join their marketplace. The request sends an email to the seller, inviting sellers to activate their store. The invitation's link in the email is unique per user, and available for only seven days for the seller to click and begin activating their store. \n\nThe email template is completely customizable. All email templates that VTEX sends to seller leads can be found and edited in the marketplace's VTEX Admin, on the Message Center section.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "CreateSellerLead", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "requestBody": { "description": "This request requires detailed information about the seller, including their email, name, account name, sales channel, and other related details. Data should be in JSON format and follow the schema specified in 'CreateSellerLeadRequest'. A sample valid payload is provided for reference, including details such as address, contact information, and acceptance of legal terms.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSellerLeadRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseCreateSellerLead" }, "example": { "sellerId": "7890123456", "createdAt": "2023-01-01T12:34:56Z", "updatedAt": "2023-01-01T12:34:56Z" } } } } }, "deprecated": false }, "get": { "tags": [ "Seller Invite" ], "summary": "List seller leads", "operationId": "ListSellerLeads", "description": "This call's response includes a list of all sellers invited by the marketplace operator to join them. Retrieved results can be filtered by adding optional query fields to the request. Each seller listed includes the following information: \n\n- `id` \n\n- `createdAt` \n\n- `status` \n\n- `isConnected` \n\n- `sellerEmail` \n\n- `sellerName` \n\n- `salesChannel` \n\n- `email`\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/isConnected" }, { "$ref": "#/components/parameters/search" }, { "$ref": "#/components/parameters/status" }, { "$ref": "#/components/parameters/orderBy" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/seller-register/pvt/seller-leads/{sellerLeadId}": { "put": { "tags": [ "Seller Invite" ], "summary": "Accept seller lead", "operationId": "AcceptSellerLead", "description": "This endpoint is triggered by the seller onboarding wizard, once the seller confirms their invitation. It can be used by marketplace operators to manually accept seller leads, and carry on with their onboarding process. \n\nNote that there's no specific API call that allows status changes. The operations only allow the seller lead to move forward: \n\n From `invite` > to `Accept` > closing on `[Create seller](https://developers.vtex.com/docs/api-reference/marketplace-apis/#put-/seller-register/pvt/seller-leads/-sellerLeadId-/seller)`. \n\nIf you want to change the status, you can start the process again, by deleting that lead through the *[Delete seller lead](https://developers.vtex.com/docs/api-reference/marketplace-apis/#delete-/seller-register/pvt/seller-leads/-sellerLeadId-)* endpoint, and resending the invite through the *[Resend seller lead's Invite](https://developers.vtex.com/docs/api-reference/marketplace-apis/#put-/seller-register/pvt/seller-leads/-sellerLeadId-/status)* endpoint. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **Save Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | Save Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/sellerId" }, { "$ref": "#/components/parameters/contentType" } ], "requestBody": { "description": "This request requires information about the seller who is accepting the lead, including their email, name, account name, sales channel, and other relevant details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptSellerLeadRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false }, "get": { "tags": [ "Seller Invite" ], "summary": "Get seller lead's data by ID", "operationId": "RetrieveSellerLead", "description": "Marketplace operators may call this endpoint to retrieve information about a specific seller invited to the Seller Portal, by searching through their seller lead ID. To retrieve the chosen seller's `sellerLeadId`, marketplace operators can use the [List Sellers](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/seller-register/pvt/sellers?endpoint=get-/seller-register/pvt/sellers) endpoint's response. Each seller listed includes the following information: \n\n- `id` \n\n- `createdAt` \n\n- `status` \n\n- `isConnected` \n\n- `sellerEmail` \n\n- `sellerName` \n\n- `salesChannel` \n\n- `email`. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/sellerId" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false }, "delete": { "tags": [ "Seller Invite" ], "summary": "Delete seller lead", "description": "This endpoint permanently deletes a seller previously invited to the marketplace, only if the seller has not yet accepted the invitation. For sellers who have already accepted the invitation, it is only possible to [pause the seller](https://help.vtex.com/en/tutorial/gerenciamento-de-sellers--6eEiOISwxuAWJ8w6MtK7iv) through the VTEX Admin. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **Save Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller Manager| Save Seller |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "RemoveSellerLead", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/sellerLeadId" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/seller-register/pvt/seller-leads/{sellerLeadId}/seller": { "put": { "tags": [ "Seller Invite" ], "summary": "Create seller from lead", "operationId": "CreateSellerFromSellerLead", "description": "This endpoint is used by marketplace operators to create seller accounts. The request will only accept seller leads whose status is `accepted`. If they are already `connected` or `invited`, the call will not be fulfilled. \n\n >\u2757 The creation of the account at VTEX is done by an internal Billing service. There is no seller account and marketplace affiliation if you do not go through this step. \n\nNote that there's no specific API call that allows status changes. The operations only allow the seller lead to move forward: \n\n From `invite` > to `Accepted` > closing on `Create Seller`. \n\nIf you want to change the status, you can start the process again, by deleting that lead through the *[Delete seller lead](https://developers.vtex.com/docs/api-reference/marketplace-apis#delete-/seller-register/pvt/seller-leads/-sellerLeadId-)* endpoint, and resending the invite through the *[Resend seller lead's invite](https://developers.vtex.com/docs/api-reference/marketplace-apis/#put-/seller-register/pvt/seller-leads/-sellerLeadId-/status)* endpoint. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **Save Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | Save Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/isActive" }, { "$ref": "#/components/parameters/sellerId" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/seller-register/pvt/seller-leads/{sellerLeadId}/status": { "put": { "tags": [ "Seller Invite" ], "summary": "Resend seller lead invite", "description": "This endpoint allows marketplace operators to resend an invitation to a seller lead who was previously invited to join their marketplace. The request will only accept seller leads whose status is `invited`. If they are already `connected` or `accepted`, the call will not be fulfilled. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **Save Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | Save Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "ResendSellerLeadRequest", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/sellerId" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "requestBody": { "description": "This request requires information specifying the action to be taken, such as the status to be resent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendSellerLeadRequestRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/seller-register/pvt/sellers/{sellerId}/commissions": { "get": { "tags": [ "Seller Commissions" ], "summary": "List seller commissions by seller ID", "description": "This endpoint retrieves all comissions configured for a specific seller. It is not necessary to send a request body.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n|---|---|---|\r\n| Seller Register | Seller adminstration | View Seller |\r\n| Seller Register | Seller administration | Save Seller |\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n|Seller manager | Save Seller | \r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\r\n\r\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "ListSellerCommissions", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/sellerId" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with objects containing information about the category, seller and percentage of commission applied.", "items": { "$ref": "#/components/schemas/responseSellerCommissionsID" } }, "example": [ { "categoryId": "51", "categoryName": "Clothes", "categoryFullPath": [ "2.0", "Boys", "Clothes" ], "productCommissionPercentage": 7.75, "freightCommissionPercentage": 2.33 } ] } } } }, "deprecated": false }, "put": { "tags": [ "Seller Commissions" ], "summary": "Upsert seller commissions in bulk", "description": "This endpoint is used by marketplace operators to define comissions for multiple categories, sending an array with multiple objects in the same call.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n|---|---|---|\r\n| Seller Register | Seller administration | Save Seller |\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n|Seller manager | Save Seller | \r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\r\n\r\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "BulkUpsertSellerCommissions", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/sellerId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "Array with objects containing information about the category, seller and commission percentage to be applied.", "items": { "$ref": "#/components/schemas/BulkUpsertSellerCommissionsRequest" } } } }, "required": true }, "responses": { "204": { "description": "No Content" } }, "deprecated": false } }, "/seller-register/pvt/sellers/{sellerId}/commissions/{categoryId}": { "delete": { "tags": [ "Seller Commissions" ], "summary": "Remove seller commissions by category ID", "operationId": "RemoveSellerCommissions", "description": "This endpoint removes a seller comission on the selected category.\r\n\r\n >❗This action cannot be undone, to reconfigure the commission it is necessary to use the [Upsert Seller Commissions in Bulk endpoint](https://developers.vtex.com/docs/api-reference/marketplace-apis#put-/seller-register/pvt/sellers/-sellerId-/commissions/categories?endpoint=put-/seller-register/pvt/sellers/-sellerId-/commissions/categories). \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n|---|---|---|\r\n| Seller Register | Seller administration | Save Seller |\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n|Seller manager | Save Seller | \r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\r\n\r\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/sellerId" }, { "$ref": "#/components/parameters/categoryId" } ], "responses": { "204": { "description": "No Content" } }, "deprecated": false }, "get": { "tags": [ "Seller Commissions" ], "summary": "Get seller commissions by category ID", "operationId": "RetrieveSellerCommissions", "description": "This endpoint retrieves seller comissions applied to the selected category. It is not necessary to send a request body.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n|---|---|---|\r\n| Seller Register | Seller administration | View Seller |\r\n| Seller Register | Seller administration | Save Seller |\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n|Seller manager | View Seller |\r\n|Seller manager | Save Seller | \r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\r\n\r\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "parameters": [ { "name": "accountName", "in": "path", "description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.", "required": true, "schema": { "type": "string", "default": "apiexamples" } }, { "name": "environment", "in": "path", "required": true, "description": "Environment to use. Used as part of the URL.", "schema": { "type": "string", "default": "vtexcommercestable" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace.", "required": true, "style": "simple", "schema": { "type": "string", "default": "seller123" } }, { "name": "categoryId", "in": "path", "description": "ID of the category in which the comission was applied", "required": true, "style": "simple", "schema": { "type": "string", "default": "6" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseSellerCommissionsID" }, "example": { "categoryId": "51", "categoryName": "Clothes", "categoryFullPath": [ "2.0", "Boys", "Clothes" ], "productCommissionPercentage": 7.75, "freightCommissionPercentage": 2.33 } } } } }, "deprecated": false } }, "/seller-register/pvt/sellers": { "post": { "tags": [ "Sellers" ], "summary": "Configure seller account", "description": "This endpoint is used by marketplace operators to configure the accounts of sellers that have already accepted the invitation to join their marketplaces. \n\nFor marketplaces to [add sellers](https://help.vtex.com/en/tutorial/adding-a-seller--tutorials_392) without the [Seller Invite](https://help.vtex.com/en/tutorial/marketplace-invited-sellers--6rb2FkcslmDueJ689Ulb9A) feature, call this endpoint directly. \n\nThis call includes all the information a seller needs to activate their account. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **Save Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | Save Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "UpsertSellerRequest", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "requestBody": { "description": "Request to upsert seller information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertSellerRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false }, "get": { "tags": [ "Sellers" ], "summary": "List sellers", "description": "This endpoint lists all sellers. The results can be filtered by [trade policies](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV) through the `sc` query param. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "GetListSellers", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/keyword" }, { "$ref": "#/components/parameters/integration" }, { "$ref": "#/components/parameters/group" }, { "$ref": "#/components/parameters/isActive" }, { "$ref": "#/components/parameters/isBetterScope" }, { "$ref": "#/components/parameters/isVtex" }, { "$ref": "#/components/parameters/sc" }, { "$ref": "#/components/parameters/sellerType" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/seller-register/pvt/sellers/{sellerId}": { "patch": { "tags": [ "Sellers" ], "summary": "Update seller by seller ID", "description": "This endpoint allows marketplace operators to update the information of sellers connected to their account. You can replace a path's value with another value in order to update that single information. There is no need to fill all the body params available, only the one you wish to update. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **Save Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | Save Seller |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "UpdateSeller", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/sellerId" } ], "requestBody": { "description": "array of objects", "content": { "application/json": { "schema": { "type": "array", "description": "array of objects", "title": "Request body", "items": { "description": "Object representing the mapping configuration between the marketplace's sales channel and the seller's affiliate channel. This configuration allows for associating a marketplace sales channel with a seller's affiliate channel for proper sales channel management.", "type": "object", "required": [ "operation", "path", "value" ], "properties": { "operation": { "type": "string", "description": "Action being performed, which should always be `replace`.", "example": "replace" }, "path": { "type": "string", "description": "Path in which the value is being updated. It follows the standardized format `/{field}`, where `{field}` is the path's name.", "example": "/field" }, "value": { "type": "boolean", "description": "Value that is being updated. Notice that the type will depend on the path that is being updated.", "example": false } } } } } } }, "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false }, "get": { "tags": [ "Sellers" ], "summary": "Get seller data by ID", "operationId": "GetRetrieveSeller", "description": "Marketplace operators may call this endpoint to retrieve information about a specific seller by filtering by ID. It is also possible to filter results by sales channel ([trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) through the `sc` query param. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "parameters": [ { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/sc" }, { "$ref": "#/components/parameters/sellerId" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/contentType" } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/seller-register/pvt/sellers/{sellerId}/sales-channel/mapping": { "put": { "tags": [ "Sales Channel Mapping" ], "summary": "Upsert sales channel mapping", "description": "This endpoint allows the marketplace to map its [trade policies](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV) with a seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187). A seller can have multiple [trade policies](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV) associated with the same marketplace, creating different affiliates. The mapping allows the seller to segment catalog, pricing, inventory, logistics, and payments in the marketplace. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager capabilities](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) in order to successfully execute this request. Otherwise, they will receive a `403` status code error. These are the applicable capabilities for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **Save seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller Manager | Save Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys typically grants permission to several [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not required, consider creating a custom role. For more information about security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "UpsertMapping", "parameters": [ { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/an" }, { "$ref": "#/components/parameters/sellerId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UpsertMappingRequest" }, "example": [ { "marketplaceSalesChannel": 1, "sellerChannel": "GCB" }, { "marketplaceSalesChannel": 2, "sellerChannel": "DFT" } ] } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "description": "Object that represents the mapping configuration between the marketplace [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV) and the seller's affiliate channel. This configuration allows you to associate a marketplace trade policy with a seller's affiliate channel for proper management of trade policies.", "type": "object", "properties": { "marketplaceSalesChannel": { "type": "string", "description": "Marketplace's trade policy that will be associated to the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187)." }, "sellerChannel": { "type": "string", "description": "Seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) that will be associated with the marketplace's trade policy. Through the affiliate, the seller determines which of his trade policy will be used for the mapping." } } } }, "example": [ { "marketplaceSalesChannel": "1", "sellerChannel": "GCC" } ] } } } }, "deprecated": false }, "get": { "tags": [ "Sales Channel Mapping" ], "summary": "Get sales channel mapping data", "description": "Retrieves information about the mapping between marketplace's sales channels and a specific seller. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Seller manager | View Seller |\r\n\r\n>\u2757 Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).", "operationId": "RetrieveMapping", "parameters": [ { "$ref": "#/components/parameters/contentType" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/accountName" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/an" }, { "$ref": "#/components/parameters/sellerId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "description": "Object representing the mapping between the marketplace's trade policy and the seller's affiliate channel. This allows for the association and management of trade policy between the marketplace and the seller's affiliate.", "type": "object", "properties": { "marketplaceSalesChannel": { "type": "string", "description": "Marketplace's sales channel that will be associated to the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187).", "default": "1" }, "sellerChannel": { "type": "string", "description": "Seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) that will be associated with the marketplace's sales channel. Through the affiliate, the seller determines which of his sales channel will be used for the mapping.", "default": "GCB" } } }, "title": "UpsertMapping", "properties": { "marketplaceSalesChannel": { "type": "integer", "description": "Marketplace's sales channel that will be associated to the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187).", "default": 1 }, "sellerChannel": { "type": "string", "description": "Seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) that will be associated with the marketplace's sales channel. Through the affiliate, the seller determines which of his sales channel will be used for the mapping.", "default": "GCB" } } }, "example": [ { "marketplaceSalesChannel": "1", "sellerChannel": "GCC" } ] } } } }, "deprecated": false } } }, "security": [ { "appKey": [], "appToken": [] } ], "components": { "schemas": { "UpsertMappingRequest": { "description": "Request to upsert a mapping between a marketplace's sales channel and a seller's affiliate.", "required": [ "marketplaceSalesChannel", "sellerChannel" ], "type": "object", "properties": { "marketplaceSalesChannel": { "type": "integer", "description": "The sales channel of the marketplace to be associated with the seller's affiliate. It is linked to the seller's affiliate.", "example": 1 }, "sellerChannel": { "type": "string", "description": "The affiliate of the seller that will be associated with the marketplace's sales channel. Through the affiliate, the seller determines which of his sales channels will be used for the mapping.", "example": "GCB" } }, "example": { "marketplaceSalesChannel": 1, "sellerChannel": "GCB" } }, "responseSellerCommissionsID": { "type": "object", "description": "Object with the category properties and the commission percentage applied to it.", "properties": { "categoryId": { "type": "string", "description": "Marketplace's category ID that the product belongs to, configured in the Catalog." }, "categoryName": { "type": "string", "description": "Category name with applied commission." }, "categoryFullPath": { "type": "array", "description": "Full path to the SKU's category.", "items": { "description": "Category level name.", "type": "string" } }, "productCommissionPercentage": { "type": "number", "description": "Percentage of the comission applied to the product in decimals." }, "freightCommissionPercentage": { "type": "number", "description": "Percentage of the comission applied to the freight in decimals." } } }, "BulkUpsertSellerCommissionsRequest": { "description": "Request to bulk upsert (update or insert) seller commission configurations for multiple categories. This includes details such as the category ID, full path of the category, product commission percentage, and freight commission percentage.", "type": "object", "required": [ "categoryId", "categoryFullPath", "productCommissionPercentage", "freightCommissionPercentage" ], "properties": { "categoryId": { "type": "string", "description": "Marketplace's Category ID that the product belongs to, configured in the Catalog.", "example": "6" }, "categoryFullPath": { "type": "string", "nullable": true, "description": "Full path to the SKU's category. It should be written as {department}/{category}. For example: if the department is **Appliances** and the category is **Oven**, the full path should be 'Appliances/Oven'.", "example": "Appliances/Oven" }, "productCommissionPercentage": { "type": "number", "description": "Percentage of the comission applied to the product in decimals.", "example": 9.85 }, "freightCommissionPercentage": { "type": "number", "description": "Percentage of the comission applied to the freight in decimals.", "example": 2.43 } }, "example": { "categoryId": "6", "categoryFullPath": null, "productCommissionPercentage": 9.85, "freightCommissionPercentage": 2.43 } }, "UpsertSellerCommissionsRequest": { "description": "Request to upsert seller commission configurations. This includes details such as the category ID, full path of the category, product commission percentage, and freight commission percentage.", "required": [ "categoryId", "categoryFullPath", "productCommissionPercentage", "freightCommissionPercentage" ], "type": "object", "properties": { "categoryId": { "type": "string", "description": "Marketplace's Category ID that the product belongs to, configured in the Catalog.", "default": "6" }, "categoryFullPath": { "type": "string", "nullable": true, "description": "Full path to the SKU's category. It should be written as {department}/{category}. For example: if the department is **Appliances** and the category is **Oven**, the full path should be 'Appliances/Oven'.", "example": "Appliances/Oven" }, "productCommissionPercentage": { "type": "number", "description": "Percentage of the comission applied to the product in decimals.", "default": 9.85 }, "freightCommissionPercentage": { "type": "number", "description": "Percentage of the comission applied to the freight in decimals.", "default": 2.43 } }, "example": { "categoryId": "6", "categoryFullPath": null, "productCommissionPercentage": 9.85, "freightCommissionPercentage": 2.43 } }, "CreateSellerLeadRequest": { "description": "Request to create a seller lead. This includes detailed information about the seller, such as their email, name, account name, trade policy, contact email, seller type, account ID, accountable person, acceptance of legal terms, address, and document details.", "required": [ "sellerEmail", "sellerName", "sellerAccountName", "salesChannel", "email", "sellerType", "accountId", "accountable", "hasAcceptedLegalTerms", "address", "document" ], "type": "object", "properties": { "sellerEmail": { "type": "string", "description": "Seller's contact email.", "example": "selleremail@email.com" }, "sellerName": { "type": "string", "description": "Seller's store's name.", "example": "Seller Name" }, "sellerAccountName": { "type": "string", "description": "Name of the seller's account, part of the url of their VTEX Admin.", "example": "seller123" }, "salesChannel": { "type": "string", "description": "Sales channel ([trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) associated to the seller account created.", "example": "1" }, "email": { "description": "The email address associated with the seller. It should be in a valid email format.", "type": "string", "example": "email@email.com" }, "sellerType": { "type": "integer", "description": "Type of seller, which can be: \n\n`1`: Regular seller \n\n`2`: White label seller.", "example": 1 }, "accountId": { "type": "string", "description": "Marketplace's account ID.", "example": "5fb38ace-d95e-45ad-970d-ee97cce9fbcd" }, "document": { "type": "string", "description": "Company's legal document number.", "example": "12345671000" }, "hasAcceptedLegalTerms": { "type": "boolean", "description": "Indicates if the seller has accepted the platform's legal terms and conditions.", "example": true }, "address": { "$ref": "#/components/schemas/address" }, "accountable": { "$ref": "#/components/schemas/accountable" } }, "example": { "sellerEmail": "selleremail@email.com", "sellerName": "Seller Name", "sellerAccountName": "seller123", "salesChannel": "1", "email": "email@email.com", "sellerType": 1, "accountId": "5fb38ace-d95e-45ad-970d-ee97cce9fbcd", "document": "12345671000", "hasAcceptedLegalTerms": true, "address": { "postalcode": "12345678", "complement": "Appartment 1234", "street": "VTEX street", "number": "25", "neighborhood": "VTEX quarter", "state": "RJ", "city": "Rio de Janeiro" }, "accountable": { "name": "Jane Smith", "email": "email@email.com", "phone": "1234567890" } } }, "responseCreateSellerLead": { "type": "object", "description": "Response object for creating a seller lead. It includes details about the created seller, such as their ID, the creation date, and the date of the last update.", "properties": { "sellerId": { "type": "string", "description": "ID of the created seller." }, "createdAt": { "type": "string", "description": "Creation date of the seller." }, "updatedAt": { "type": "string", "description": "Date of the last update of the seller." } } }, "accountable": { "type": "object", "description": "Details of the person accountable for the seller's account. This includes their name, email address, and phone number.", "required": [ "name", "email", "phone" ], "properties": { "name": { "type": "string", "description": "Name of the person responsible for the seller.", "example": "Jane Smith" }, "email": { "type": "string", "description": "Email address of the person responsible for the seller.", "example": "email@email.com" }, "phone": { "type": "string", "description": "Phone number of the person responsible for the seller.", "example": "1234567890" } } }, "address": { "type": "object", "description": "Details of the address associated with the seller. This includes postal code, complement, street, number, neighborhood, state, and city.", "required": [ "postalcode", "complement", "street", "number", "neighborhood", "state", "city" ], "properties": { "postalcode": { "type": "string", "description": "Postal code from the seller's address.", "example": "12345678" }, "complement": { "type": "string", "description": "Seller's address complement.", "example": "Appartment 1234" }, "street": { "type": "string", "description": "Street information, from the seller's address.", "example": "Park Avenue" }, "number": { "type": "string", "description": "Street's number, from the seller's address.", "example": "25" }, "neighborhood": { "type": "string", "description": "Seller's address neighborhood.", "example": "Manhattan" }, "state": { "type": "string", "description": "State, from the seller's address.", "example": "RJ" }, "city": { "type": "string", "description": "City name, from the seller's address.", "example": "Rio de Janeiro" } } }, "AcceptSellerLeadRequest": { "description": "Request to accept a seller lead. This includes detailed information about the seller, such as their email, name, account name, trade policy, contact email, seller type, account ID, document details, acceptance of legal terms, address, and accountable party.", "required": [ "sellerEmail", "sellerName", "sellerAccountName", "salesChannel", "email", "sellerType", "accountId", "document", "hasAcceptedLegalTerms", "address", "accountable" ], "type": "object", "properties": { "sellerEmail": { "type": "string", "description": "Seller's contact email.", "example": "selleremail@email.com" }, "sellerName": { "type": "string", "description": "Seller's store's name.", "example": "Seller Name" }, "sellerAccountName": { "type": "string", "description": "Name of the seller's account, part of the url of their VTEX Admin.", "example": "seller123" }, "salesChannel": { "type": "string", "description": "Sales channel ([trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) associated to the seller account created.", "example": "1" }, "email": { "type": "string", "description": "email of the admin responsible for the seller.", "example": "seller@email.com" }, "sellerType": { "type": "integer", "description": "Type of seller, including: \n\n`1`: Regular seller \n\n`2`: White label seller.", "example": 1 }, "accountId": { "type": "string", "description": "Marketplace's account ID.", "example": "5fb38ace-d95e-45ad-970d-ee97cce9fbcd" }, "document": { "type": "string", "description": "Company's legal document code.", "example": "12345671000" }, "hasAcceptedLegalTerms": { "type": "boolean", "description": "Indicates if the seller has accepted the platform's legal terms and conditions.", "example": true }, "address": { "$ref": "#/components/schemas/address" }, "accountable": { "$ref": "#/components/schemas/accountable" } } }, "ResendSellerLeadRequestRequest": { "description": "Request to resend a seller lead. This includes the status of the lead that determines the action to be taken.", "required": [ "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Seller lead's status, which can be: `accepted`, `connected` or `invited`.", "example": "accepted" } } }, "UpsertSellerRequest": { "title": "Configure Seller Account", "description": "Request to configure or update a seller account. This includes all necessary details for setting up the seller's account, such as ID, name, status, fulfillment settings, payment options, tax information, contact details, commission configuration, policies, and authentication information.", "required": [ "id", "name", "isActive", "fulfillmentEndpoint", "allowHybridPayments", "taxCode", "email", "description", "sellerCommissionConfiguration", "isBetterScope", "sellerType", "availableSalesChannels", "CSCIdentification", "account", "channel", "salesChannel", "isVtex", "score", "exchangeReturnPolicy", "deliveryPolicy", "securityPrivacyPolicy", "fulfillmentSellerId", "user", "password", "catalogSystemEndpoint", "trustPolicy" ], "type": "object", "properties": { "id": { "type": "string", "description": "Seller ID assigned by the marketplace. We recommend filling it in with the seller's account name.", "example": "seller123" }, "name": { "type": "string", "description": "Name of the seller's store, configured in the seller's environment.", "example": "Seller Name" }, "isActive": { "type": "boolean", "description": "Whether the seller is active on the marketplace or not.", "example": true }, "fulfillmentEndpoint": { "type": "string", "description": "URL of the endpoint for fulfillment of seller's orders, which the marketplace will use to communicate with the seller. \n\nFor **external sellers**, please include the URL of the seller's endpoint. External sellers have different endpoint standards. The seller must inform this endpoint to the marketplace so that the marketplace can complete the configuration process. \n\nFor **VTEX Stores**, the field format will be as follows: `https://{SellerName}.vtexcommercestable.com.br/api/fulfillment?&sc={TradePolicyID}`. \n\nThe value `SellerName` corresponds to the store name if the seller is a VTEX store. \n\nThe value `TradePolicyID` corresponds to the [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV#master-data) created by the seller in their own VTEX environment. The seller must inform this ID to the marketplace so that the marketplace can complete the configuration process. \n\nThe value `AffiliateID` corresponds to the 3-digit affiliate identification code created by the seller. The seller must inform this ID to the marketplace so that the marketplace can complete the configuration process. \n\nTo configure the [Multilevel Omnichannel Inventory](https://developers.vtex.com/vtex-rest-api/docs/multilevel-omnichannel-inventory) feature, fill in this field with the checkout endpoint following this example: `https://{{sellerAccount}}.vtexcommercestable.com.br/api/checkout?affiliateid={{affiliateId}}&sc={{salesChannel}}`.", "example": "http://{SellerName}.vtexcommercestable.com.br/api/fulfillment?&sc={TradePolicyID}" }, "allowHybridPayments": { "type": "boolean", "description": "Indicates if customers can use gift cards from the seller to buy their products on the marketplace (`true`) or not (`false`). If true, it identifies purchases made with a gift card so that only the final price (with discounts applied) is paid to the seller.", "example": false }, "taxCode": { "type": "string", "description": "Identity number of the legal entity, which is linked to information in its base country.", "example": "34444" }, "email": { "type": "string", "description": "Email of the administrative user responsible for the seller.", "example": "seller@email.com" }, "description": { "type": "string", "description": "Description of the seller.", "example": "Seller A, from the B industry." }, "sellerCommissionConfiguration": { "description": "Details of the seller's commission configuration, including the product commission percentage, freight commission percentage, and categories commission configuration.", "type": "object", "items": { "$ref": "#/components/schemas/SellerCommissionConfiguration" }, "example": { "productCommissionPercentage": 3.0, "freightCommissionPercentage": 4.0, "categoriesCommissionConfiguration": [] } }, "isBetterScope": { "type": "boolean", "description": "Flag used by the VTEX Checkout to simmulate shopping carts, products and shipping only in sellers with the boolean set as `true`, avoiding performance issues.", "example": true }, "sellerType": { "type": "integer", "description": "Type of seller, including: \n\n`1`: Regular seller \n\n`2`: White label seller.", "example": 1 }, "availableSalesChannels": { "type": "array", "items": { "$ref": "#/components/schemas/AvailableSalesChannel" }, "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) available.", "example": [ { "isSelected": true, "id": 1, "name": "Principal store" }, { "isSelected": true, "id": 2, "name": "Third" }, { "isSelected": true, "id": 3, "name": "Marketplaces" } ] }, "CSCIdentification": { "type": "string", "description": "SKU Seller Identification.", "example": "cscidentification 123" }, "account": { "type": "string", "description": "Seller's account name.", "example": "partner01" }, "channel": { "type": "string", "description": "Channel's name.", "example": "channel name" }, "salesChannel": { "type": "string", "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) associated to the seller account created. If no value is specified, the system will automatically use the sales channel configured in the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) ID.", "example": "1" }, "isVtex": { "type": "boolean", "description": "Indicates whether the seller configured is a VTEX store or not.", "example": true }, "exchangeReturnPolicy": { "type": "string", "description": "Text describing the exchange and return policy previously agreed between the marketplace and the seller.", "example": "Describe exchange and returns policy" }, "deliveryPolicy": { "type": "string", "description": "Text describing the delivery policy previously agreed between the marketplace and the seller.", "example": "Describe delivery policy" }, "securityPrivacyPolicy": { "type": "string", "nullable": true, "description": "Text describing the security policy previously agreed between the marketplace and the seller.", "example": "Our marketplace ensures that all transactions are encrypted with SSL technology, and we adhere to strict privacy standards to protect both sellers and buyers. Personal data is only shared with authorized parties to facilitate order processing and delivery, and we do not sell or disclose personal information to third parties without consent." }, "fulfillmentSellerId": { "type": "string", "description": "Identification code of the seller responsible for fulfilling the order. This is an optional field used when a seller sells SKUs from another seller. If the seller sells their own SKUs, it must be nulled.", "nullable": true, "example": "seller1" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Groups" }, "description": "Array of groups attached to the seller. Groups are defined by keywords that group sellers into categories defined by the marketplace when adding a new seller through the [Configure Seller Account](https://developers.vtex.com/docs/api-reference/marketplace-apis?endpoint=post-/seller-register/pvt/sellers) endpoint. It is possible to filter sellers by group in the Seller Management page in your VTEX Admin. Learn more about groups through our [Seller Management](https://help.vtex.com/en/tutorial/seller-management--6eEiOISwxuAWJ8w6MtK7iv#groups) documentation.", "example": [ { "groups": [ { "id": "8d845239bf1448dc8bc3ed3121837511", "name": "long tail" }, { "id": "b9bcd348ab9c4cec8285ff9485c27a72", "name": "franchise accounts" } ] } ] }, "user": { "type": "string", "description": "Username, if you are using a hub to integrate with the external seller.", "example": "integrationHubUserName", "nullable": true }, "password": { "type": "string", "description": "User password, if you are using a hub to integrate with the external seller.", "example": "integrationHubPassword", "nullable": true }, "catalogSystemEndpoint": { "type": "string", "description": "URL of the endpoint of the seller's catalog. This field will only be displayed if the seller type is VTEX Store. The field format will be as follows: `https://{sellerName}.vtexcommercestable.com.br/api/catalog_system/`.", "example": "https://apiexamples.vtexcommercestable.com.br/api/catalog_system/" }, "trustPolicy": { "type": "string", "description": "Specifies the trust policy agreed between the marketplace and the seller, such as permissions related to data sharing.", "example": "AllowEmailSharing" }, "score": { "type": "number", "description": "Score attributed to this seller.", "example": 0.0 } } }, "SellerCommissionConfiguration": { "description": "Configuration details for seller commissions. This includes the product commission percentage, freight commission percentage, and categories commission configuration.", "required": [ "productCommissionPercentage", "freightCommissionPercentage", "categoriesCommissionConfiguration" ], "type": "object", "properties": { "productCommissionPercentage": { "type": "number", "description": "Percentage of the comission applied to the product in decimals.", "example": 9.85 }, "freightCommissionPercentage": { "type": "number", "description": "Percentage of the comission applied to the freight in decimals.", "example": 2.43 }, "categoriesCommissionConfiguration": { "type": "array", "description": "Array containing the commission configurations for different categories. Each item in the array specifies the category and the commission percentage applied to it.", "items": { "type": "object", "description": "Object representing the commission configuration for a specific category. This includes the category identifier or name and the commission percentage applied to it.", "properties": { "category": { "type": "string", "description": "Category identifier or name.", "example": "electronics" }, "commission": { "type": "number", "description": "Percentage of the commission applied to the category in decimal format.", "example": 0.15 } }, "required": [ "category", "commission" ] }, "default": [] } }, "example": { "productCommissionPercentage": 3.0, "freightCommissionPercentage": 4.0, "categoriesCommissionConfiguration": [] } }, "AvailableSalesChannel": { "description": "Details of a trade policy available for the product. This includes whether the sales channel is selected, its ID, and its name.", "required": [ "isSelected", "id", "name" ], "type": "object", "properties": { "isSelected": { "type": "boolean", "description": "Defines if the sales channel ([trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) is selected or not.", "example": true }, "id": { "type": "integer", "description": "Trade policy ID.", "example": 1 }, "name": { "type": "string", "description": "Name of the trade policy.", "example": "Principal store" } } }, "Groups": { "title": "groups", "description": "Array of groups attached to the seller. Groups are defined by key-words that group sellers into categories defined by the marketplace when adding a new seller through the [Configure Seller Account](https://developers.vtex.com/vtex-rest-api/reference/sellers#putupsertseller) endpoint. It is possible to filter sellers by group in the Seller Management page in your VTEX Admin. Know more about groups through our [Seller Management](https://help.vtex.com/en/tutorial/gerenciamento-de-sellers-beta--6eEiOISwxuAWJ8w6MtK7iv#groups) documentation.", "required": [ "groups" ], "type": "object", "properties": { "id": { "type": "string", "description": "Group's unique identifier code.", "example": "8d845239bf1448dc8bc3ed3121837511" }, "name": { "type": "string", "description": "Name of the tag chosen to identify the group.", "example": "Franchise accounts" } }, "example": { "groups": [ { "id": "8d845239bf1448dc8bc3ed3121837511", "name": "long tail" }, { "id": "b9bcd348ab9c4cec8285ff9485c27a72", "name": "franchise accounts" } ] } }, "Sku2": { "description": "Details of the SKU (Stock Keeping Unit) associated with the product. This includes the SKU ID, EAN ID, reference ID, complete name, short name, active status, main image, and offers.", "required": [ "SkuId", "EanId", "RefId", "NameComplete", "Name", "IsActive", "MainImage", "Offers" ], "type": "object", "properties": { "SkuId": { "type": "string", "description": "SKU's unique identifier number." }, "EanId": { "type": "string", "nullable": true, "description": "EAN's unique identifier number." }, "RefId": { "type": "string", "nullable": true, "description": "SKU's Reference ID." }, "NameComplete": { "type": "string", "description": "Complete name of the SKU." }, "Name": { "type": "string", "description": "Summarized name of the SKU." }, "IsActive": { "type": "boolean", "description": "Whether the SKU is active in the trade policy (true), or not (false).", "default": true }, "MainImage": { "type": "object", "description": "Main image's information.", "items": { "$ref": "#/components/schemas/MainImage" } }, "Offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" }, "description": "Array with offers." } } }, "MainImage": { "description": "Details of the main image associated with the product. This includes the image's ID, label, tag, path, and other attributes indicating its main and zoom size status, as well as additional text and last modification date.", "required": [ "ImageId", "ImageLabel", "ImageTag", "ImagePath", "IsMain", "IsZoomSize", "ImageText", "LastModified" ], "type": "object", "properties": { "ImageId": { "type": "string", "description": "Code identifying the image's file." }, "ImageLabel": { "type": "string", "nullable": true, "description": "Image's label." }, "ImageTag": { "type": "string", "description": "HTML tag for the selected image." }, "ImagePath": { "type": "string", "description": "Path for the image's file." }, "IsMain": { "type": "boolean", "description": "Whether the image is the main one or not.", "default": true }, "IsZoomSize": { "type": "boolean", "description": "If zoom can be applied to the image.", "default": true }, "ImageText": { "type": "string", "description": "Alt text for the image." }, "LastModified": { "type": "string", "description": "Date of the last change made to the image." } } }, "Offer": { "description": "Details of an offer provided by a seller. This includes the seller's identification, SKU, offers per sales channel, and available trade policies.", "required": [ "SellerId", "SellerSkuId", "OffersPerSalesChannel", "AvailableSalesChannels" ], "type": "object", "properties": { "SellerId": { "type": "string", "description": "ID of the seller in the marketplace. This ID must be created by the marketplace." }, "SellerSkuId": { "type": "string", "description": "Unique identifier of the SKU in the seller. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications." }, "OffersPerSalesChannel": { "type": "array", "description": "Each element in the array corresponds to an offer in a specific trade policy.", "items": { "$ref": "#/components/schemas/OffersPerSalesChannel" } }, "AvailableSalesChannels": { "type": "string", "nullable": true, "description": "The sales channel ([trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) ID in which the SKU is available." } } }, "OffersPerSalesChannel": { "title": "OffersPerSalesChannel", "description": "Details of offers available per trade policy. This includes pricing information and available quantity specific to each trade policy.", "required": [ "SaleChannel", "Price", "ListPrice", "PriceWithoutDiscount", "AvailableQuantity" ], "type": "object", "properties": { "SaleChannel": { "type": "integer", "description": "Sales channel ([trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) of the SKU." }, "Price": { "type": "integer", "description": "SKU's price." }, "ListPrice": { "type": "integer", "description": "SKU's suggested selling price." }, "PriceWithoutDiscount": { "type": "integer", "description": "SKU's price without discount applied." }, "AvailableQuantity": { "type": "integer", "description": "Available SKU stock quantity." } } }, "responseGetMatchedOffersList": { "type": "array", "description": "Response with the list of offers available on the Marketplace.", "items": { "type": "object", "description": "Array of SKUs in the offer.", "properties": { "LastModified": { "type": "string", "description": "Last date when the offer was modified." }, "ProductId": { "type": "string", "description": "Unique identifier of the seller's product. This is the ID that the marketplace will use for all references to this product." }, "CategoryId": { "type": "integer", "description": "Offer's Category ID that the product belongs to, configured in the Catalog. It should be the marketplace's category chosen for the offer to be matched with." }, "BrandId": { "type": "integer", "description": "Offer's brand ID that the product belongs to, configured in the Catalog. It should be the marketplace's brand chosen for the offer to be matched with." }, "ProductName": { "type": "string", "description": "Name of the offer's product." }, "Skus": { "type": "array", "description": "A list of SKUs (Stock Keeping Units) associated with the product. Each SKU contains detailed information about specific variants of the product, such as color, size, and other specifications.", "items": { "$ref": "#/components/schemas/Sku2" } } } } }, "responseGetMatchedOffersDataBySKU": { "description": "Array of matched offers data by SKU.", "type": "array", "items": { "type": "object", "description": "Schema for individual offer data.", "properties": { "productId": { "type": "string", "description": "Unique identifier for the product." }, "skuId": { "type": "string", "description": "Unique identifier for the product SKU." }, "nameComplete": { "type": "string", "description": "Complete name of the product." }, "mainImage": { "type": "object", "description": "Schema for the main product image.", "required": [ "imagePath" ], "properties": { "imagePath": { "type": "string", "description": "File path of the main product image." } } }, "sellersOffers": { "type": "array", "description": "Array of offers from different sellers.", "items": { "type": "object", "description": "Schema for individual seller offer data.", "properties": { "sellerId": { "type": "string", "description": "Unique identifier for the seller." }, "sellerSkuId": { "type": "string", "description": "Unique identifier for the seller's SKU." }, "salesChannelOffer": { "type": "array", "description": "Array of offers on different trade policies from the same seller.", "items": { "type": "object", "description": "Schema for individual trade policy offer data.", "properties": { "salesChannelId": { "type": "string", "description": "Unique identifier for the trade policy." }, "salesChannelName": { "type": "string", "description": "Name of the trade policy." }, "price": { "type": "number", "description": "Offer price." }, "listPrice": { "type": "number", "description": "List price of the product." }, "priceWithoutDiscount": { "type": "number", "description": "Offer price without any discount." }, "availableQuantity": { "type": "integer", "description": "Available quantity of the product." } } } } } } } } } }, "responseGetMatchedOffersDataByProductId": { "type": "array", "description": "Array of matched offers data by product ID.", "items": { "type": "object", "description": "Schema for individual offer data.", "properties": { "productId": { "type": "string", "description": "Unique identifier for the product." }, "skuId": { "type": "string", "description": "Unique identifier for the product SKU." }, "nameComplete": { "type": "string", "description": "Complete name of the product." }, "mainImage": { "type": "object", "description": "Schema for the main product image.", "required": [ "imagePath" ], "properties": { "imagePath": { "type": "string", "description": "File path of the main product image." } } }, "sellersOffers": { "type": "array", "description": "Array of offers from different sellers.", "items": { "type": "object", "description": "Schema for individual seller offer data.", "properties": { "sellerId": { "type": "string", "description": "Unique identifier for the seller." }, "sellerSkuId": { "type": "string", "description": "Unique identifier for the seller's SKU." }, "salesChannelOffer": { "type": "object", "description": "Schema for the offer data on a specific sales channel (trade policy).", "properties": { "salesChannelId": { "type": "string", "description": "Unique identifier for the sales channel (trade policy)." }, "salesChannelName": { "type": "string", "description": "Name of the trade policy." }, "price": { "type": "number", "description": "Offer price." }, "listPrice": { "type": "number", "description": "List price of the product." }, "priceWithoutDiscount": { "type": "number", "description": "Offer price without any discount." }, "availableQuantity": { "type": "integer", "description": "Available quantity of the product." } } } } } } } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } }, "parameters": { "isBetterScope": { "name": "isBetterScope", "in": "query", "description": "The flag `isBetterScope` is used by the VTEX Checkout to simulate shopping carts, products, and shipping only in sellers with the field set as `true`, avoiding performance issues. When used as a query param, `isBetterScope` filters sellers that have the flag set as `true` or `false`.", "required": false, "schema": { "type": "boolean", "default": false } }, "isConnected": { "name": "isConnected", "in": "query", "description": "Query param that enables results to be filter by whether the seller lead is already connected to the marketplace or not.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "" } }, "search": { "name": "search", "in": "query", "description": "Custom search field, that filters sellers invited by specific marketplace operator's email.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "user email" } }, "status": { "name": "status", "in": "query", "description": "Seller Lead's status. Includes `accepted`, `connected` or `invited`.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "invited" } }, "orderBy": { "name": "orderBy", "in": "query", "description": "Query param determining how data will be ordered in the response, ordering by name or ID in descending our ascending order. Includes the following values: \n\n`namesort` = desc/asc \n\n`idsort` = desc/asc", "required": true, "style": "form", "explode": true, "schema": { "type": "string" } }, "limit": { "name": "limit", "in": "query", "description": "This field determines the limit used to retrieve the list of sellers. The response includes objects until the value inputted here. ", "required": true, "style": "form", "explode": true, "schema": { "type": "integer", "default": 15 } }, "offset": { "name": "offset", "in": "query", "description": "This field determines the limit used to retrieve the list of sellers. The response includes objects starting `from` the value inputted here.", "required": true, "style": "form", "explode": true, "schema": { "type": "integer", "default": 0 } }, "categoryId": { "name": "categoryId", "in": "path", "description": "ID of the category in which the comission was applied", "required": true, "style": "simple", "schema": { "type": "string", "default": "6" } }, "sellerLeadId": { "name": "sellerLeadId", "in": "path", "description": "ID of the Seller Lead invited to the marketplace.", "required": true, "style": "simple", "schema": { "type": "string" } }, "from": { "name": "from", "in": "query", "description": "The start number of pagination, being `0` the default value.", "required": false, "schema": { "type": "number", "default": 0 } }, "to": { "name": "to", "in": "query", "description": "The end number of pagination, being `100` the default value.", "required": false, "schema": { "type": "number", "default": 100 } }, "keyword": { "name": "keyword", "in": "query", "description": "Search sellers by a keyword in `sellerId` or `sellerName`.", "required": false, "schema": { "type": "string", "default": "keyword" } }, "integration": { "name": "integration", "in": "query", "description": "Filters sellers by the name of who made the integration, if VTEX or an external hub. The possible values for VTEX integrations are: `vtex-sellerportal`, `vtex-seller` and `vtex-franchise`.", "required": false, "schema": { "type": "string", "default": "vtex-seller" } }, "group": { "name": "group ", "in": "query", "description": "Groups are defined by keywords that group sellers into categories defined by the marketplace.", "required": false, "schema": { "type": "string", "default": "Group" } }, "isActive": { "name": "isActive", "in": "query", "description": "Enables to filter sellers that are active (`true`) or unactive (`false`) in the marketplace.", "required": false, "schema": { "type": "boolean", "default": false } }, "accountName": { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account that belongs to the marketplace. The notification will be posted into this account.", "schema": { "type": "string", "example": "apiexamples" } }, "contentType": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, "environment": { "name": "environment", "in": "path", "required": true, "description": "Environment to use. Used as part of the URL.", "schema": { "type": "string", "default": "vtexcommercestable" } }, "accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, "sellerId": { "name": "sellerId", "in": "path", "description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.", "required": true, "style": "simple", "schema": { "type": "string", "example": "seller123" } }, "skuId": { "name": "skuId", "in": "path", "description": "A string that identifies the seller's SKU that suffered the change. This is the ID that the marketplace will use for all references to this SKU, such as price and inventory notifications.", "required": true, "style": "simple", "schema": { "type": "string", "example": "1234" } }, "sort": { "name": "sort", "in": "query", "description": "Criteria used to sort the list of offers. For sorting values in ascending order, use `asc`, while for descending order, use `desc`. To fill in the field, insert the sorting criteria, followed by 'asc', or 'desc', separated by a comma. You can sort by the following criteria: \n\n- **price:** sorts offers by price. *Ascending* goes from lowest to highest price, while *Descending* goes from highest to lowest price. \n\n- **name:** sorts offers by *productName*, in alphabetical order. *Ascending* goes from *A* to *Z*, while *Descending* goes from *Z* to *A*. \n\n- **availability:** availability in the sales channel (sc). The default value is 1. \n\nEx. sort=availability,desc \n\nEx. sort=name,asc \n\nEx. price,desc", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "availability,desc" } }, "rows": { "name": "rows", "in": "query", "description": "Number of rows included in the response. Each row corresponds to a single offer. The default amount of rows in the response is 1, and the maximum amount is 50. To have more than one offer listed in the response, please add the `rows` parameter with a number greater than 1.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 20 } }, "start": { "name": "start", "in": "query", "description": "Number corresponding to the row from which the offer list will begin, used for pagination. Filters the list of offers by retrieving the offers starting from the row defined. The default value is 0, if the param is not included in the call.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "default": 0 } }, "fq": { "name": "fq", "in": "query", "description": "This filter query can be used to filter offers by the criteria described below. It should be filled in by following the format: `fq={{criteriaName}}:{{criteriaValue}}`. \n\n- **productId:** integer of the product ID \n\n- **productName:** string of the product's name \n\n- **skuId:** integer of the SKU ID \n\n- **eanId:** string of the EAN ID \n\n- **refId:** string of the Ref ID \n\n- **categoryId:** integer of the category ID \n\n- **brandId:** integer of the brand ID \n\n- **sellerId:** string of the seller ID \n\n- **sc:** integer of the sales channel's ID (trade policy in VTEX) \n\nEx: skuId:172 \n\nEx: categoryId:13 \n\nEx. productName:Product example-123", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "skuId:172" } }, "productId": { "name": "productId", "in": "path", "description": "A string that identifies the seller's product. This is the ID that the marketplace will use for all references to this product, such as price and inventory notifications.", "required": true, "style": "simple", "schema": { "type": "string", "example": "123456" } }, "an": { "name": "an", "in": "query", "description": "Marketplace's account name, the same one inputted on the endpoint's path.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "default": "apiexamples" } }, "sc": { "name": "sc", "in": "query", "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) associated to the seller account created.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "default": "1" } }, "sellerType": { "name": "sellerType", "in": "query", "description": "Filters sellers by their type, which can be regular seller (`1`) or whitelabel seller (`2`).", "required": false, "schema": { "type": "integer", "default": 1 } }, "isVtex": { "name": "isVtex", "in": "query", "description": "When set as `true`, the list returned will be of sellers who have a VTEX store configured. When set as `false`, the list will be of sellers who do not have a VTEX store configured.", "required": false, "schema": { "type": "boolean", "default": false } } } }, "tags": [ { "name": "Sellers" }, { "name": "Seller Invite" }, { "name": "Seller Commissions" }, { "name": "Notification" }, { "name": "Matched Offers" }, { "name": "Sales Channel Mapping" } ] }